home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / msdos / raytrace / pov / gen / form04a / docs / language.doc < prev    next >
Text File  |  1994-02-03  |  7KB  |  283 lines
  1. LANGUAGE.DOC
  2.  
  3. This is a brief description of the interface and language
  4. of form. This file is updated very sporadically so I'm sorry about
  5. the lack of organisation to it. For command line flags see form.doc 
  6. or defaults.doc
  7.  
  8. Pressing <ESC> during a display should stop the display
  9.  
  10.  
  11.  
  12. KEYWORDS/PHRASES
  13. #include "filename"
  14. copyright
  15. CopyrIgHt
  16. COpyRIghT...and so on
  17. lexdebug on
  18. lex debug off
  19. yaccdebug on
  20. yaccdebug off
  21. plg scale
  22. screen_scale
  23. screen_res
  24. display wire
  25. display gouraud
  26. display flat
  27. display phong
  28. sphere
  29. cone
  30. ellipse
  31. spacer
  32. box
  33. torus
  34. stack
  35. stack in
  36. grow
  37. bend
  38. twist
  39. twistx
  40. twistz
  41. centered_grow
  42. powered_grow
  43. powered_centered_grow
  44. delete 
  45. delete to
  46. web
  47. fan
  48. move
  49. with
  50.  
  51.  
  52.  
  53. usage:
  54.     form    [options] [file] [options]
  55.    if [file] is ommited the form is read from stdin
  56.    options are also read from the environment variable FORM, and sstools.ini
  57.  
  58.  
  59.                      *******   ****   *****   **   **
  60.                      *        *    *  *    *  * * * *
  61.                      ****     *    *  *****   *  *  *
  62.                      *        *    *  * *     *     *
  63.                      *        *    *  *  *    *     *
  64.                      *         ****   *   *   *     *
  65.  
  66.  
  67.  
  68. C style comments are allowed both /**/ and // forms
  69.  
  70. SYMBOL is a standard C symbol ie. a-z followed by any of a-z 0-9 and _.
  71. NUMBERS are all real, converted to int wherever appropriate.  
  72. NUMBERS can be expressions using +, -, *, /, ^, ().
  73. VECTORS are in the form "<" real "," real "," real ">"
  74. ANGLES are in degrees
  75.  
  76.  
  77. The form file essentially describes a scene.
  78. it has the shape of :-
  79.  
  80. any number of: objectdefinitions
  81. any number of: debug flag assignments
  82. any number of: configurable item assignments
  83. any number of: output commands (currently only display!)
  84. at least ONE: object        (usually only one)
  85. optionally terminated with the word "end" (meaning produce some output)
  86. simple end of file simply stops processing
  87.  
  88.  
  89. OBJECT
  90. ======
  91. an object is a set of part objects terminated by a ';'
  92.  
  93. a (part) object is :
  94.  
  95. an object followed by a FORM
  96. an object followed by a simple modifier
  97. an object followed by a FORM modifier 
  98. a PRIMITIVE
  99. a DEFINED_OBJECT
  100. a DEFINED_OBJECT enclosed by "[ ]", this has the effect of rotating
  101.                  the object by 90 degrees
  102. an object "," object.
  103.  
  104.  
  105. OBJECT DEFINITION 
  106. =================
  107. is a name (symbol) followed by "=" and then an object.
  108.  
  109.  
  110.  
  111. COMMANDS
  112. ========
  113.  
  114. DEBUG RELATED COMMANDS
  115. ----------------------
  116.  
  117. these have no effect on the objects or output
  118.  
  119. lexdebug <on|off>   turns debug prinouts from lex on or off (default off)
  120.  
  121. yaccdebug <on|off>  turns debug prinouts from yacc on or off (default off)
  122.  
  123. yydebug <on|off>    turns internal yacc debug prints on or off (default off)
  124.  
  125. OUTPUT RELATED COMMANDS
  126. -----------------------
  127. these affect the output not the shape
  128.  
  129. plg scale = number; 
  130.                 defines the plg scale used for output to plg - default 500
  131.  
  132. old_pov_method;     
  133.                 not used anymore
  134.  
  135. screen_res   = [1|2|3];   
  136.                 equivalent to -res[1|2|3] command line option
  137.  
  138. screen_scale = number;
  139.                 scale up the screen output, 1.2 is usually OK
  140.  
  141. display [object] [save file name] [rendering style];
  142.                 will display object (default current object) in the
  143.                 rendering style specified. save file name is not
  144.                 actually implemented, it takes time but doesn't do
  145.                 anything. This does not in any way represent the
  146.                 views of the author to freeware, it's just I haven't
  147.                 done it yet!
  148.  
  149.  
  150. PRIMITIVES
  151. ==========
  152.  
  153. sphere  
  154. sphere radius 
  155.  
  156. ellipse
  157. ellipse width , height
  158. ellipse <vector>            (vector gives x, y, z axis lengths)
  159.  
  160. box
  161. box size
  162. box vector                   (vector gives x , y , z size)
  163.  
  164. torus
  165. torus minradius , maxradius
  166.  
  167. spacer
  168. spacer size                 (unseen object only used for spacing)
  169.  
  170. cone
  171. cone baseradius, height
  172.  
  173. FORMS
  174. =====
  175.  
  176. these take an object (list of objects) and create another object from
  177. a compound of these to which have been applied transformations
  178.  
  179. STACK number_to_stack
  180. STACK number_to_stack IN space_of_number 
  181. STACK number_to_stack IN space_percentage "%"
  182.  
  183.     This stacks number_to_stack objects with compression of:
  184.     1.0
  185.     space_of_number / number_to_stack
  186.     space_percentage / 100
  187.             
  188. The resulting object is similar to that created by a list of objects
  189.             i.e. sphere stack 2 is the same as sphere , sphere
  190.             
  191. FAN   number , angle [ , tightness]
  192.  
  193.     takes no_objs copies of object and fans them through 0 .. angle
  194.     degrees in a sphere (angle usually 0 .. 180), optional tightness
  195.     defaults to 1 gives a bunching effect, 0.1 shows what it does the
  196.     result is a single object of height 0;
  197.  
  198. web   number1 WITH defined_object 
  199.             [SCALE(number2)] number3 [hole number] [excess number]
  200.  
  201.     uses number1 spokes of object webbed with number3 of defined object
  202.     which are optionally scaled up by number2.!
  203.     hole is the gap to leave in the middle (2 = 2 * length of a spoke)
  204.     excess is amount to exceed by (proportions of a spoke)
  205.     eg. 
  206.         spokeobject WEB 8 WITH webbing_object 3
  207.         creates a sort of 8 spoked 3 ringed waggon-wheel.
  208.  
  209. rib     NYI
  210.  
  211.  
  212. MODIFIERS
  213. =========
  214.  
  215. these are applied to an object and are used to change the shape
  216.  
  217. SIMPLE MODIFIERS
  218. ----------------
  219.  
  220. DELETE delete_range e.g delete 1   or delete 10 .. 5
  221.     makes the x..y'th object in the list invisible.
  222.  
  223. MOVE <vector>
  224.     moves every object in the list by vector (remember Y is up)
  225.  
  226. TEXTURE <texture name> eg texture "Metal pigment{White}"
  227.     applies the POV texture from that point downwards.
  228.  
  229. STACK MODIFIERS
  230. ---------------
  231.  
  232. these give a warning if they do not follow a stack but will often
  233. work if there is a list of more than one object
  234.  
  235. GROW    size    
  236.  
  237.     takes the stack and uniformly grows each object (about it's own
  238.     center) by an amount: 1 for the first object, and size for the
  239.     last. 
  240.  
  241. POWERED_GROW    
  242. CENTERED_GROW
  243. POWERED_CENTERED_GROW
  244.     slightly different in how they actually do the growing. 
  245.     Not too hot. Powered grow is the best of the lot, it isn't
  246.     linear, that's all.
  247.  
  248. BEND    angle   
  249.  
  250.     bends the stack fromthe vertical by angle. Bend of 360 gives one
  251.     loop of a spiral, bend of 90 gives a quarter loop.
  252.  
  253. TWIST   angle [ , displacement]
  254.  
  255.     rotates each obj in stack around vertical axis by 0 .. angle
  256.     degrees optional offset moves stack by displcement, rotates about
  257.     original axis and then moves back. Gives a spiral effect
  258.  
  259. TWISTX   angle 
  260.     rotates each obj in stack around X axis by 0 .. angle.
  261.  
  262. TWISTZ   angle 
  263.     rotates each obj in stack around vertical axis by 0 .. angle.
  264.     interesting effect when combined with BEND.
  265.  
  266. incremental twist   ILLEGAL
  267. incremental grow    ILLEGAL
  268. incremental bend    ILLEGAL
  269.  
  270.  
  271. OTHER VALID INPUT
  272. =================
  273.  
  274. exists      test token
  275.  
  276. end         marks EndOfFile, REQUIRED or you don't get any output!
  277.  
  278. include "filename"
  279.  
  280.         rummy@snaffle.demon.co.uk
  281.  
  282.         Andrew Rowbottom
  283.